+2006-04-17 Emmanuele Bassi <ebassi@cvs.gnome.org>
+
+ * gtk/tmpl/gtkrecent*.sgml: Add long descriptions.
+
2006-04-16 Matthias Clasen <mclasen@redhat.com>
* gtk/tmpl/gtkrecent*.sgml: Add short descriptions
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+#GtkRecentChooser is an interface that can be implemented by widgets
+displaying the list of recently used files. In GTK+, the main objects
+that implement this interface are #GtkRecentChooserWidget,
+#GtkRecentChooserDialog and #GtkRecentChooserMenu.
</para>
+
<para>
Recently used files are supported since GTK+ 2.10.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+#GtkRecentManager, #GtkRecentChooserDialog, #GtkRecentChooserWidget,
+#GtkRecentChooserMenu
</para>
<!-- ##### SECTION Stability_Level ##### -->
@item_activated:
@selection_changed:
-<!-- ##### MACRO GTK_RECENT_CHOOSER_ERROR ##### -->
+
+<!-- ##### SIGNAL GtkRecentChooser::item-activated ##### -->
<para>
</para>
+@recentchooser: the object which received the signal.
+<!-- ##### SIGNAL GtkRecentChooser::selection-changed ##### -->
+<para>
-<!-- ##### ENUM GtkRecentChooserError ##### -->
+</para>
+
+@recentchooser: the object which received the signal.
+
+
+
+<!-- ##### MACRO GTK_RECENT_CHOOSER_ERROR ##### -->
<para>
+Used to get the #GError quark for #GtkRecentChooser errors.
+</para>
+
+
+<!-- ##### ENUM GtkRecentChooserError ##### -->
+<para>
+These identify the various errors that can occur while calling
+#GtkRecentChooser functions.
</para>
-@GTK_RECENT_CHOOSER_ERROR_NOT_FOUND:
-@GTK_RECENT_CHOOSER_ERROR_INVALID_URI:
+@GTK_RECENT_CHOOSER_ERROR_NOT_FOUND: Indicates that a file does not exist
+@GTK_RECENT_CHOOSER_ERROR_INVALID_URI: Indicates a malformed URI
<!-- ##### FUNCTION gtk_recent_chooser_set_show_private ##### -->
<para>
<!-- ##### SECTION Long_Description ##### -->
<para>
+#GtkRecentChooserDialog is a dialog box suitable for displaying the recently
+used documents. This widgets works by putting a #GtkRecentChooserWidget inside
+a #GtkDialog. It exposes the #GtkRecentChooserIface interface, so you can use
+all the #GtkRecentChooser functions on the recent chooser dialog as well as
+those for #GtkDialog.
+</para>
+<para>
+Note that #GtkRecentChooserDialog does not have any methods of its own.
+Instead, you should use the functions that work on a #GtkRecentChooser.
</para>
+
+<example id="gtkrecentchooser-typical-usage">
+ <title>Typical usage</title>
+
+ <para>
+ In the simplest of cases, you can use the following code to use
+ a #GtkRecentChooserDialog to select a recently used file:
+ </para>
+
+ <programlisting>
+GtkWidget *dialog;
+
+dialog = gtk_recent_chooser_dialog_new ("Recent Documents",
+ parent_window,
+ GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
+ GTK_STOCK_OPEN, GTK_RESPONSE_ACCEPT,
+ NULL);
+
+if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
+ {
+ GtkRecentInfo *info;
+
+ info = gtk_recent_chooser_get_current_item (GTK_RECENT_CHOOSER (dialog));
+ open_file (gtk_recent_info_get_uri (info));
+ gtk_recent_info_unref (info);
+ }
+
+gtk_widget_destroy (dialog);
+ </programlisting>
+</example>
+
<para>
Recently used files are supported since GTK+ 2.10.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+#GtkRecentChooser, #GtkDialog
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+#GtkRecentChooserMenu is a widget suitable for displaying recently used files
+inside a menu. It can be used to set a sub-menu of a #GtkMenuItem using
+gtk_menu_item_set_submenu(), or as the menu of a #GtkMenuToolButton.
</para>
+
+<para>
+Note that #GtkRecentChooserMenu does not have any methods of its own. Instead,
+you should use the functions that work on a #GtkRecentChooser.
+
<para>
Recently used files are supported since GTK+ 2.10.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+#GtkRecentChooser
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+#GtkRecentChooserWidget is a widget suitable for selecting recently used
+files. It is the main building block of a #GtkRecentChooserDialog. Most
+applications will only need to use the latter; you can use
+#GtkRecentChooserWidget as part of a larger window if you have special needs.
</para>
+
+<para>
+Note that #GtkRecentChooserWidget does not have any methods of its own.
+Instead, you should use the functions that work on a #GtkRecentChooser.
+
<para>
Recently used files are supported since GTK+ 2.10.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+#GtkRecentChooser, #GtkRecentChooserDialog
</para>
<!-- ##### SECTION Stability_Level ##### -->
GtkRecentFilter
<!-- ##### SECTION Short_Description ##### -->
-A filter for recently used files
+A filter for selecting a subset of recently used files
<!-- ##### SECTION Long_Description ##### -->
<para>
+A #GtkRecentFilter can be used to restrict the files being shown
+in a #GtkRecentChooser. Files can be filtered based on their name
+(with gtk_recent_filter_add_pattern()), on their mime type (with
+gtk_file_filter_add_mime_type()), on the application that has
+registered them (with gtk_recent_filter_add_application()), or by
+a custom filter function (with gtk_recent_filter_add_custom()).
+</para>
+<para>
+Filtering by mime type handles aliasing and subclassing of mime
+types; e.g. a filter for text/plain also matches a file with mime
+type application/rtf, since application/rtf is a subclass of text/plain.
+Note that #GtkRecentFilter allows wildcards for the subtype of a
+mime type, so you can e.g. filter for image/*.
</para>
+
+<para>
+Normally, filters are used by adding them to a #GtkRecentChooser,
+see gtk_recent_chooser_add_filter(), but it is also possible to
+manually use a filter on a file with gtk_recent_filter_filter().
+</para>
+
<para>
Recently used files are supported since GTK+ 2.10.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+#GtkRecentChooser
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT GtkRecentFilter ##### -->
<para>
-
+The <structname>GtkRecentFilter</structname> struct contains
+only private fields and should not be directly accessed.
</para>
<!-- ##### STRUCT GtkRecentFilterInfo ##### -->
<para>
-
+A <structname>GtkRecentFilterInfo</structname> struct is used
+to pass information about the tested file to gtk_recent_filter_filter().
</para>
-@contains:
-@uri:
-@display_name:
-@mime_type:
-@applications:
-@groups:
-@age:
+@contains: Flags indicating which of the following fields need
+ are filled
+@uri: the URI of the file being tested
+@display_name: the string that will be used to display the file
+ in the recent chooser
+@mime_type: the mime type of the file
+@applications: the list of applications that have registered the file
+@groups: the groups to which the file belongs to
+@age: the number of days elapsed since the file has been registered
<!-- ##### ENUM GtkRecentFilterFlags ##### -->
<para>
-
+These flags indicate what parts of a #GtkRecentFilterInfo struct
+are filled or need to be filled.
</para>
-@GTK_RECENT_FILTER_URI:
-@GTK_RECENT_FILTER_DISPLAY_NAME:
-@GTK_RECENT_FILTER_MIME_TYPE:
-@GTK_RECENT_FILTER_APPLICATION:
-@GTK_RECENT_FILTER_GROUP:
-@GTK_RECENT_FILTER_AGE:
+@GTK_RECENT_FILTER_URI: the URI of the file being tested
+@GTK_RECENT_FILTER_DISPLAY_NAME: the string that will be used to
+ display the file in the recent chooser
+@GTK_RECENT_FILTER_MIME_TYPE: the mime type of the file
+@GTK_RECENT_FILTER_APPLICATION: the list of applications that have
+ registered the file
+@GTK_RECENT_FILTER_GROUP: the groups to which the file belongs to
+@GTK_RECENT_FILTER_AGE: the number of days elapsed since the file
+ has been registered
<!-- ##### USER_FUNCTION GtkRecentFilterFunc ##### -->
<para>
-
+The type of function that is used with custom filters,
+see gtk_recent_filter_add_custom().
</para>
-@filter_info:
-@user_data:
-@Returns:
+@filter_info: a #GtkRecentFilterInfo that is filled according
+ to the @needed flags passed to gtk_recent_filter_add_custom()
+@user_data: user data passed to gtk_recent_filter_add_custom()
+@Returns: %TRUE if the file should be displayed
<!-- ##### FUNCTION gtk_recent_filter_new ##### -->
<!-- ##### SECTION Long_Description ##### -->
<para>
-
-</para>
+#GtkRecentManager provides a facility for adding, removing and
+looking up recently used files. Each recently used file is
+identified by its URI, and has meta-data associated to it, like
+the names and command lines of the applications that have
+registered it, the number of time each application has registered
+the same file, the mime type of the file and whether the file
+should be displayed only by the applications that have
+registered it.
+</para>
+
+<para>
+The #GtkRecentManager acts like a database of all the recently
+used files. You can create new #GtkRecentManager objects, but
+it is more efficient to use the standard recent manager for
+the #GdkScreen so that informations about the recently used
+files is shared with other people using them. In case the
+default screen is being used, adding a new recently used
+file is as simple as:
+</para>
+
+<informalexample>
+ <programlisting>
+GtkRecentManager *manager;
+GError *error = NULL;
+
+manager = gtk_recent_manager_get_default ();
+gtk_recent_manager_add_item (manager, file_uri, &error);
+if (error)
+ {
+ g_warning ("Could not add the file: %s", error->message);
+ g_error_free (error);
+ }
+ </programlisting>
+</informalexample>
+
+While looking up a recently used file is as simple as:
+
+<informalexample>
+ <programlisting>
+GtkRecentManager *manager;
+GtkRecentInfo *info;
+GError *error = NULL;
+
+manager = gtk_recent_manager_get_default ();
+info = gtk_recent_manager_lookup_item (manager, file_uri, &error);
+if (error)
+ {
+ g_warning ("Could not find the file: %s", error->message);
+ g_error_free (error);
+ }
+else
+ {
+ /* Use the info object */
+ g_object_unref (info);
+ }
+ </programlisting>
+</informalexample>
<para>
Recently used files are supported since GTK+ 2.10.
<!-- ##### STRUCT GtkRecentManager ##### -->
<para>
-
-</para>
+Acts as a database of information about the list of recently
+used files. Normally, you retrieve the recent manager for a
+particular screen using gtk_recent_manager_get_for_screen()
+and it will contain information about current recent manager
+for that screen.</para>
<!-- ##### STRUCT GtkRecentInfo ##### -->
<para>
-
+Contains informations found when looking up an entry of the
+recently used files list.
</para>
<!-- ##### STRUCT GtkRecentData ##### -->
<para>
-
-</para>
-
-@display_name:
-@description:
-@mime_type:
-@app_name:
-@app_exec:
-@groups:
-@is_private:
+Meta-data passed to gtk_recent_manager_add_full(). You should
+use #GtkRecentData if you want to control the meta-data associated
+to an entry of the recently used files list when you are adding
+a new file to it.
+</para>
+
+@display_name: the string to be used when displaying the file
+ inside a #GtkRecentChooser
+@description: a user readable description of the file
+@mime_type: the mime type of the file
+@app_name: the name of the application that is registering
+ the file
+@app_exec: the command line that should be used when launching
+ the file
+@groups: the list of group names to which the file belongs to
+@is_private: whether the file should be displayed only by
+ the applications that have registered it
<!-- ##### MACRO GTK_RECENT_MANAGER_ERROR ##### -->
<para>
projects / gtk4.git / commitdiff